# -*- coding: utf-8 -*-
# @Time    : 2024/7/19 13:28
# @Author  : yujiahao
# @File    : 46_fastapi_matadata_url.py
# @description:元数据和文档 URL


# 在 FastAPI 中，元数据和文档 URL 是非常重要的功能，主要用于生成和定制 API 文档。这些功能不仅提高了开发和维护 API 的效率，还增强了 API 的可用性和可读性

"""
API 元数据
在 FastAPI 应用程序中，你可以自定义多个元数据配置。这些元数据配置将用于设置 OpenAPI 规范和自动生成的 API 文档 UI。

注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（login）以及「fancy」会显示为斜体（fancy）。

以下是可以使用的字段：

参数             类型    描述
--------------------------------------
title            str     API 的标题。
summary          str     API 的简短摘要。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。
description      str     API 的简短描述。可以使用 Markdown。
version          str     API 的版本。这是您自己的应用程序的版本，而不是 OpenAPI 的版本。例如 2.5.0。
terms_of_service str     API 服务条款的 URL。如果提供，则必须是 URL。
contact          dict    公开的 API 的联系信息。它可以包含多个字段。

    - name: str, 联系人的名字。
    - url: str, 联系人的 URL。
    - email: str, 联系人的电子邮件地址。
license_info     dict    公开的 API 的许可证信息。它可以包含多个字段。

    - name: str, 许可证的名称。
    - url: str, 许可证的 URL。

"""

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

# 标签元数据
# 让我们在带有标签的示例中为 users 和 items 试一下。
# 创建标签元数据并把它传递给 openapi_tags 参数
# 这是给users和items的标签

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

# API元数据

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
    openapi_tags=tags_metadata  # 这个是标签元数据
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]


# 使用你的标签
# 将 tags 参数和路径操作（以及 APIRouter）一起使用，将其分配给不同的标签

@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


# 使用你的标签
# 将 tags 参数和路径操作（以及 APIRouter）一起使用，将其分配给不同的标签
@app.get("/items_1/", tags=["items"])
async def get_items_1():
    return [{"name": "wand"}, {"name": "flying broom"}]


"""
【标签顺序】

每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。

例如，按照字母顺序，即使 `users` 排在 `items` 之后，它也会显示在前面，因为我们将它的元数据添加为列表内的第一个字典。




【OpenAPI URL】

默认情况下，OpenAPI 模式服务于 `/openapi.json`。全部版本的

但是你可以通过参数 `openapi_url` 对其进行配置。

例如，将其设置为服务于 `/api/v1/openapi.json`：可以是特定版本的

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")

@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

如果你想完全禁用 OpenAPI 模式，可以将其设置为 `openapi_url=None`，这样也会禁用使用它的文档用户界面。




【文档 URLs】
你可以配置两个文档用户界面，包括：

1. Swagger UI：服务于 `/docs`。
   - 可以使用参数 `docs_url` 设置它的 URL。
   - 可以通过设置 `docs_url=None` 禁用它。

2. ReDoc：服务于 `/redoc`。
   - 可以使用参数 `redoc_url` 设置它的 URL。
   - 可以通过设置 `redoc_url=None` 禁用它。

例如，设置 Swagger UI 服务于 `/documentation` 并禁用 ReDoc：

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)

@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]
"""
